In this section all resources needed to integrate remote documentation into your library implementation in ADOxx are provided.

• Download Resources for Integration

  3 files need to be available in your library (to get all in a package, use the ZIP download below):

  • RemoteDocumentation.asc: this AdoScript enables the communication between your tool and the web-service. It acts as a client to retrieve a list of available reports, uploads the necessary files for the report to the server, triggers the report generation and downloads the results.
  • wget.exe: to enhance the platform functionality, the wget.exe is needed to run downloads/crawls of the results. You can download wget.exe from the developer (http://gnuwin32.sourceforge.net/packages/wget.htm) or as part of the package below.
  • curl.exe: to enhance the platform functionality, the curl.exe is needed to run uploads of input files to the server. You can download curl.exe from the developer (http://curl.haxx.se/) or as part of the package below.
  PACKAGED DOWNLOAD (all in one)

• Extract package and Import into Library

  Extract the package of above on your local harddrive and import the 3 files contained into your library (see Video tutorial)

• Add menu entry to trigger remote documentation

  Add the following lines to your library configuration (Dynamic Library -> Library attributes -> External coupling) to add a new menu entry. Alternatively you can also trigger the service from a button or programmcall (details on triggering an AdoScript can be found online here).

  ATTENTION: Make sure to adapt the URL if you have deployed the service at a different location.

  #################################################################
  ######## REMOTE DOCUMENTATION TRIGGER ########
  #################################################################
  ITEM "Create remote documentation" importexport:"Documentation"
  SETG sRemoteDocumentationURL:""
  EXECUTE file:("db:\\RemoteDocumentation.asc")

In this section we provide details on how to update/change/modify the implementation according to your specific needs. The source code of the service is available in the SVN repository. The project is developed using Maven as a dependency management and build system, therefore the initial build will make sure that all resources/libraries are needed are downloaded from web repositories. In case you are new to Maven, have a look a the brief introduction online here (Maven in 5 minutes)

• Service Architecture

  The service is built using the Apache Cocoon as a transformation framework. Available transformation pipelines are made available via a registry, exposed as a webservice. The registry provides dynamically configuration parameters to the client (report format, model selection mode) and triggers the necessary pipeline when requested.

  Apache Cocoon enables a modular implementation of transformations (so called "blocks"), whereas each block is a seperate Maven project. For the RemoteDocumentation service one block is defined (can be run in debug mode without any further work), this block is added as a Maven dependency to the WebApplication project. The figure below provides an abstract view on the block available for the documentation service.

  

• Integration View

  From an external perspective, the service enables the generation flow by providing the necessary pipelines/matchers to the client. The AdoScript client allows the integration in ADOxx-based modelling tools in 4 steps, from the registry retrieval to download and storage of the report.

  

• 1. Trigger Report Selection:

  Each reported provided by the service needs to be registered. Reports are registered in a common format providing configuration and pipeline information. See an example below. The registry is available as an XML file stored in src/main/resources/COB-INF/registry/registry.xml

  <report>
    <name>PDF (Content, Multiple)</name>
    <format>*.pdf</format>
    <filedesc>PDF</filedesc>
    <multi-select>1</multi-select>
    <pipeline>modelContentPDF/</pipeline>
  </report>

  <report> : for each report configuration, a new report tag is added to the file

  <name> : the human readable report name, displayed for user selection in ADOxx-based tool

  <format> : the file type to be used for this report, starting with a *. and the file extension)

  <filedesc> : a readable file description for display in the export dialog

  <multi-select> : 1|0 as a boolean value, if multiple models should be selected

  <pipeline> : matcher to be used for the export/download of the report. In case a single model is exported and is used in the pipeline, use MODELID as a placeholder.

  The registry of this deployment is available here as XML and here for configuration of the LISTBOX in AdoScript.

• 2. Report Config:

  Details on a report are retrieved by name. An example call is /transformationRegistry/PDF (Content, Multiple) . The result of this call is the configuration set provided in the registry.

• 3. Content Upload:

  A special pipeline has been implemented as an action in the block. The pipeline accepts multipart request elements and an ID to upload files and store them in the content folder of the deployment. The file part should be named uploaded_file , the unique ID to create a new folder on the server userDir

• 4. Report Download:

  The pipeline parameter from the registry is used to download and store the report.

• Developmente View: SVN/GIT Repository

  To get ready for development checkout the 2 projects (webapp and block as shown above) to your local workspace/IDE. For debugging the block project ADOxxWeb ModelDocu Block is your starting point.

  1. To compile the project open a command shell/use your preferred Maven enabled IDE and run mvn clean install . This will clean the target directory and re-build your project.

  2. To debug the project, run mvn jetty:run . This will start a jetty instance on port 8888 and the block can be debugged/developed.

  3. For deployment, get the second project ADOxxWeb RemoteDocumentation and run mvn clean install . This will create the remote_docu.war file in your target folder for deployment, including the dependent block of above.

• Further information

  Apache Cocoon 2.2, incl. Tutorials and First Steps

  ADOxx.org Documentation